TIFF256 Graphics Library Extensions For C Programmers Version 3.0 July 28, 1994 Copyright Spyro Gumas, 1992 - 1994. All Rights Reserved Look what You get for Registering!! - Royalty Free Use of TIFF256 in Your Programs! - 3D Graphics Library! - Graphics Mouse Library! - Joystick Library & Source Code! - Image Processing Library & Source Code! - Graphical User Interface Library & Source Code - 32 Bit WATCOM C Compiler compatible library! - On line support through CompuServe! - Printed Users Manual and Software Disk! - Half Price upgrade to next version! (See Page 6 for Details) Page: 1 1.0 Introduction 3 1.1 Revision History 4 1.2 Benefits of Registering 6 1.3 Distribution Files 7 1.4 Some TIFF Insight 7 2.0 The TIFF256 Extensions Environment 8 2.1 Using The TIFF256 Extensions 8 2.2 Global Graphics Parameters 8 2.3 Compiler Compatibility 9 2.4 Support of TIFF 5.0 9 3.0 TIFF256 Extensions Functionality 12 3.1 Handling The Color Look Up Table 12 3.2 Function Descriptions 13 3.2.1 tf_set_true_color_mode 13 3.2.2 tf_get_true_color_mode 14 3.2.3 tf_open_file 14 3.2.4 tf_close_file 14 3.2.5 tf_get_file_info 15 3.2.6 tf_skip_ifd 15 3.2.7 tf_set_defaults 16 3.2.8 tf_read_ifd 16 3.2.9 tf_display_ifd 17 3.2.10 tf_save_file 18 3.2.11 tf_image_size 19 3.2.12 tf_load_image 19 3.2.13 tf_save_image 20 3.2.14 tf_set_prime_colors 21 4.0 Nitty Gritties 22 4.1 Registration Information 22 4.2 Software License 23 4.3 Disclaimer 24 4.4 Technical Support 24 5.0 Appendix 25 5.1 TIFF.H Include File 25 Page: 2 1.0 Introduction The TIFF256 Graphics Library Extensions Version 3.0 is a library of C routines which extend the capabilities of the VSA256 Graphics Library. With TIFF256 the C programmer has the tools necessary to read, display, and write Tagged Image File Format (TIFF) images using a 256 color video adapter running with the VESA BIOS Extensions. Support is provided for both Microsoft C and Borland C products. The name "TIFF256" reflects the fact that this library supports the 256 color video modes defined within the VESA standard. As the preeminent graphics format, TIFF images have permeated the fiber of the computer world. It is the single most common file format supported by virtually all hand held and flat bed scanners. While every major computer platform has evolved its own unique image file format, TIFF is the one standard format which crosses the boundaries between PC, MAC, Silicon Graphics, Sun, HP, DEC, and all the rest. The TIFF256 Graphics Library Extensions lets you take advantage of TIFF's popularity by letting you integrate TIFF capability into your graphical application. While powerful and robust, the TIFF256 library is simple to use. Only a few lines of code are required to get a TIFF image up on the screen. One more line of code and the image is saved. (By the way, have you ever tried to write out a BMP image under Windows? ... Good night Eunice!) A few more lines of code and you can customize how the software displays 24 bit/pixel images on your 256 color display, selecting between 332 RGB, Dithered, or Adaptive Palette displays. The VSA256 / TIFF256 combination gives you a formidable tool for graphical programming while sparing you the nightmare of Windows programming. Page: 3 1.1 Revision History -Version 1.0 is the original SHAREWARE version of the TIFF256 Graphics Library Extensions. -Version 2.0b is the REGISTERED version of the TIFF256 Graphics Library Extensions. Whereas the TIFF256 Graphics Library Extensions Version 1.x is shareware, Version 2.0b IS NOT shareware and may only be used in accordance with the terms of the purchase agreement. The major change between version 1.0 and 2.0b is the addition of the routine called tf_save_file. With this one new routine, the programmer may now create a TIFF file from any image generated using the VSA256 Graphics Library and the TIFF256 Graphics Library Extensions. -Version 3.0 is presented to the general public in the true spirit of shareware. This revision is the full-up version of the TIFF256 Graphics Library Extensions. I no longer maintain a separate registered version of this library. Version 3.0 of the TIFF256 Graphics Library Extensions is presented as Shareware with high hopes that the programmers who use this library will feel good about sending in the registration fee of $29. The major changes between version 2.0b and 3.0 are listed below: **Added Adaptive Palette - Now the programmer has the option to turn on Adaptive Palette during the 24 bits/pixel to 8 bits/pixel color reduction. The Adaptive Palette feature calculates the optimum color palette for each True Color image. The result is that the most reduced images retain their True Color look. **Added Dithering - The programmer has the option to turn on dithering during the 24 bits/pixel to 8 bits/pixel color reduction. Dithering approximates the full 16 million color spectrum on 256 color systems through a technique of jittering or dithering pixel intensities. This technique is particularly useful when a good adaptive palette can not be generated. **New routine, tf_set_true_color_mode - Used to select 8 bit RGB, Dithering, or Adaptive Palette for True Color images and to define the Adaptive Palette configuration. **New routine, tf_get_true_color_mode - Used to get current True Color display mode and Adaptive Palette configuration parameters. **New routine, tf_image_size - Used to get the size of an image for use with next two functions. **New routine, tf_load_image - Now you can read a TIFF file directly into an memory buffer instead of having to display it on the screen first. Use vsa_put_image to display it on the screen when you are ready. Page: 4 **New routine, tf_save_image - With this function you can save an image already in a memory buffer to a TIFF file. You can use vsa_get_image to copy screen image into memory buffer. **Clipping when TIFF image displayed on screen - This is an outcome of the VSA256 Graphics Library 3.0 upgrade which added clipping. You no longer have to worry about your images screen wrapping. **Fixed "unresolved external _fstrlen" linker error with Turbo C. **Made all functions in TIFF.H external, no more "Multiple Declaration" warnings. **Changed name of tf_display_image to tf_display_ifd - Since tf_load_image, tf_save_image, vsa_get_image, and vsa_put_image all use 'image' in the context of a memory buffer, consistency demands this change. tf_display_ifd doesn't deal with memory buffers but goes straight from a TIFF file to the screen. For compatibility with older versions, tf_display_image in old code automatically gets mapped to a call to tf_display_ifd. **Turned off automatic error message screen output - Now the application can decide whether or not it wants an error message actually displayed by interpreting the return values of the relevant functions. Page: 5 1.2 Benefits of Registering If you use this program beyond an initial evaluation period, you must register your use with a $29 remittance to the author .. me ($15 if ordering VSA256 and TIFF256 at the same time, see ORDER.TXT). In addition to the good feeling that you get for sustaining a late night hacking obsession, you get the following benefits for registering: 1) Royalty Free Use of TIFF256 in Your Programs! Feel free to distribute your programs for profit with no royalty fees. See section 4.2. 2) 3D Graphics Library! Don't live in a flat world. Add the missing 3rd dimension to your creations. This library lets you create 3d objects, set your view point, and perform 3d transformations including scale, offset, and rotation. Supports wireframe, solid, and Gouraud shaded objects. 3) Graphics Mouse Library! Use this library to integrate Mouse input with your graphics applications. Get precise updates of mouse position, update screen cursor, read mouse buttons, and more. Invent your own graphical user interface, give your apps that professional feel, have tons of fun! 4) Joystick Library with Source Code! Integrate Joystick input with your graphics applications. Write a flight simulator, boat driver, or your own unique use of this agile input device. 5) IMP256 Image Processing Library and Source Code! With this library you can learn all about image sharpening, embossing, blurring, color balancing, and enhancement. 6) 32 Bit WATCOM C Compiler compatible VSA256 and TIFF256 libraries! Get the edge on performance. 7) On line support through CompuServe. 8) Printed Users Manual and Current Version Software on Disk. 9) One Half Price Upgrade to the next version, as it becomes available. AND 10) The following public domain full color TIFF image files to get you started: VENUS.TIF EARTH.TIF MOON.TIF MARS.TIF SATURN.TIF Page: 6 NEPTUNE.TIF SHUTTLE.TIF ASTRONTS.TIF WEATHER.TIF MANDRILL.TIF 1.3 Distribution Files The distribution of the TIFF256 Graphics Library Extensions Version 3.0 consists of the 8 files listed below. These files are archived in the file TIF256.ZIP. To extract, just type 'PKUNZIP TIF256' in the directory that you want the files extracted to. TIF_DEMO.C Demonstration program (Source Code). TIF_DEMO.EXE Demonstration program (Executable). TIF_DATA.EXE TIFF file analysis program (Executable). TIFFMSL.LIB TIFF256 Extensions, Large Memory Model (Microsoft C). TIFFBCL.LIB TIFF256 Extensions, Large Memory Model (Borland C). TIFF.H Include file required in your program. TIFF256.TXT This text document. ORDER.TXT A text file order form for upgrades and registration. 1.4 Some TIFF Insight A TIFF file can contain one or more images. Each of these images is stored in the file as an "Image File Directory" (an IFD). Each IFD consists of numerous fields or "tags". Each tag defines a particular aspect of the image (i.e. color model, width, length, resolution, etc.). With the TIFF256 Extensions, a programmer can find out how many IFDs are contained within a TIFF file, jump to the desired IFD, read all of the tags within the IFD, and display the IFD's image. Page: 7 2.0 The TIFF256 Extensions Environment 2.1 Using The TIFF256 Extensions The TIFF256 Extensions work with any (any?) IBM PC, XT, AT or compatible computer equipped with a VESA compatible SVGA video adapter card capable of 256 colors. Most of the video cards sold today are VESA compatible with the VESA BIOS built in to the card. For older SVGA video cards which are not VESA compatible, the VESA BIOS Extensions must be loaded as a Terminate and Stay Resident (TSR) program before using the TIFF256 Extensions. A math coprocessor chip is not required. The TIFF256 Extensions are distributed as a Large Memory Model library for either Microsoft C or Borland C. If other memory models are required, contact me. The TIFF256 Extensions Version 3.0 are used in conjunction with the VSA256 Graphics Library Version 3.0. The following discussion assumes that you are adding TIFF capability to an existing program which already uses the VSA256 Graphics Library. To use the TIFF256 Extensions, add the file TIFF.H to your C compiler's default directory for INCLUDE files, add the statement: #include; to your program, and add the file TIFFBCL.LIB or TIFFMSL.LIB to the list of files that your program is linked with. 2.2 Global Graphics Parameters The file TIFF.H is used as an include file during program development. This file includes all of the extension's function prototypes and it defines the global parameters that describe the TIFF File and individual IFDs. The global graphics parameters are initialized by the tf_get_file_info() and tf_read_ifd() functions and are described below: TF_Num_Ifd: Unsigned, the number of IFDs in the TIFF file. TF_ImageWidth: Unsigned long, the image width in pixels. TF_ImageLength: Unsigned long, the image length in pixels. TF_BitsPerSample[3]: Unsigned, the number of bits per sample. For Bilevel, grayscale, or Palette Color, pixel size = TF_BitsPerSample[0]. For True Color, pixel Red Component = TF_BitsPerSample[0], pixel Green component = TF_BitsPerSample[1], pixel Blue component = TF_BitsPerSample[2]. TF_ResolutionUnit: Unsigned, 1 = Not specified, 2 = Inch, 3 = Centimeter. TF_SamplesPerPixel: Unsigned, the number of samples per pixel. TF_PhotometricInterpretation: Unsigned, 1 = Bilevel or Grayscale, 2 = RGB (True Color) image, 3 = Palette Color Image. Page: 8 TF_XResolution_int: Unsigned long, the integral number of pixels in the x dimension per TF_ResolutionUnit. TF_XResolution_frac: Unsigned long, the fractional number of pixels in the x dimension per TF_ResolutionUnit. TF_YResolution_int: Unsigned long, the integral number of pixels in the y dimension per TF_ResolutionUnit. TF_YResolution_frac: Unsigned long, the fractional number of pixels in the y dimension per TF_ResolutionUnit. TF_Black: Unsigned, index into CLUT for color nearest to black. TF_Red: Unsigned, index into CLUT for color nearest to Red. TF_Orange: Unsigned, index into CLUT for color nearest to Orange. TF_Yellow: Unsigned, index into CLUT for color nearest to Yellow. TF_Green: Unsigned, index into CLUT for color nearest to Green. TF_Aqua: Unsigned, index into CLUT for color nearest to Aqua. TF_Blue: Unsigned, index into CLUT for color nearest to Blue. TF_Violet: Unsigned, index into CLUT for color nearest to Violet. TF_White: Unsigned, index into CLUT for color nearest to White. 2.3 Compiler Compatibility The TIFFMSL.LIB was compiled using Microsoft's Quick C 2.5 and it seems to also work well with Microsoft C 6.0 and 7.0. I have received reports of compatibility problems with Microsoft C 5.0. The TIFFBCL.LIB was compiled using Borland's C/C++ 3.1 and it seems to also work well with Borland C/C++ 3.0 and 4.0. I have received conflicting reports of compatibility problems with Borland's Turbo C 2.0 and 3.0. I appreciate any feedback that programmers send me along these lines so that I can continue to improve this product. Important Note for Borland Users: You Must set the -Fs compiler option. This tells the compiler to assume that the Stack Segment equals the Data Segment. In the Programmers IDE, you go to Options / Compiler / Code Generation and select "Always" under the option "Assume SS Equals DS". Why? Because I compiled the TIFF256 Extensions with the -Fs option set for compatibility with VSA256 Graphics Library. Why did I compile VSA256 with the -Fs option? See the VSA256 documentation, section 2.3 if you really must know. 2.4 Support of TIFF 5.0 For the programmer familiar with the TIFF 5.0 Technical Memorandum, the following list indicate which and to what degree the Page: 9 defined tags are supported by the TIFF256 Extensions. The tags supported provide functionality with most images. When in doubt, run the provided TIF_DATA program to determine the characteristics of a given TIFF file. TAGS SUPPORTED: Basic Tags - BitsPerSample = 8,8,8 (for RGB or True Color Images) BitsPerSample <= 8 (for Bilevel, Grayscale, or Palette images) ColorMap Compression = none ImageLength ImageWidth NewSubFileType PhotometricInterpretation = Bilevel and Grayscale PhotometricInterpretation = RGB (True Color) PhotometricInterpretation = Palette Color PlanarConfiguration = 1 ResolutionUnit RowsPerStrip SamplesPerPixel StripByteCounts StripOffsets XResolution YResolution TAGS NOT SUPPORTED (Maybe Next Revision): Basic Tags - BitsPerSample != 8,8,8 (for RGB or True Color Images) BitsPerSample > 8 (for Bilevel, Grayscale, or Palette images) ColorResponseCurves Compression = CCITT Group 3 1-Dimensional Modified Huffman RLE Compression = LZW Compression Compression = PackBits Compression GrayResponseCurve GrayResponseUnit PhotometricInterpretation = Transparency Mask PlanarConfiguration = 2 Predictor Page: 10 TAGS NOT SUPPORTED (continued): Informational Tags - Artist DateTime HostComputer ImageDescription Make Model Software Facsimile Tags - Group3Options Group4Options Document Storage and Retrieval Tags - DocumentName PageName PageNumber XPosition YPosition Obsolete Tags - CellLength CellWidth FillOrder FreeByteCounts FreeOffsets MaxSampleValue MinSampleValue SubFileType Orientation Thresholding Page: 11 3.0 TIFF256 Extensions Functionality This section describes the operation of the TIFF256 Extensions. To use the functions in this library, compile your program using the Large Memory Model and link your program with the appropriate libraries listed below depending on the compiler being used. Microsoft C or Quick C - VSA256MS.LIB and TIFFMSL.LIB Borland C++ or Turbo C - VSA256BC.LIB and TIFFBCL.LIB 3.1 Handling The Color Look Up Table The TIFF256 Extensions supports Bilevel and 8 bit or less Grayscale images (TF_PhotometricInterpretation = 1), 24 bit True Color images (TF_PhotometricInterpretation = 2) and 8 bit or less Palette Color images (TF_PhotometricInterpretation = 3). Since this library is specifically designed for hardware with 256 entry Color Look Up Tables (CLUTs), 24 bit True Color images are reduced to 8 bit images. The method of reduction is selectable as either 332-RGB, Dithered, or Adaptive Palette . With the 332-RGB method, the Red, Green, and Blue color components are compressed to 8 bit pixels consisting of 3 bits Red, 3 bits Green, and 2 bits Blue, and the CLUT is loaded with a compressed True Color palette. The Dithered method also loads a compressed True Color palette, but the pixel intensities are modulated (or dithered) in a technique which approximates all of the 16 million possible colors. With the Adaptive Palette method each 24 bit image is analyzed separately. The optimal color palette is determined for the image and loaded into the Color Look Up Table (see section 3.2.1 'tf_set_true_color_mode' function for details). For Palette Color images, the IFD comes with its own values which are directly loaded into the CLUT. Regardless of image type, the CLUT is not loaded until 'tf_display_ifd' (section 3.2.9) is called, even though the IFD may have already been read by 'tf_read_ifd' (section 3.2.8). This means that the previously loaded CLUT (typically from previously displayed IFD) remains in force until 'tf_display_ifd' is called. When using, 'tf_load_image' (section 3.2.12) instead of 'tf_display_ifd', the CLUT is not loaded until the program deems appropriate with a call to 'vsa_write_color_block'. Page: 12 3.2 Function Descriptions In the following sections each function is listed along with a definition of its inputs and return values. A description is provided followed by any relevant comments. 3.2.1 tf_set_true_color_mode(mode,num_colors,quality) Inputs: int mode, num_colors, quality; Returns: Nothing Description: This routine configures the way that 24 bit/pixel True Color images are displayed. When reading an image from an IFD, the 'tf_display_ifd' and 'tf_load_image' routines automatically detect the number of bits per pixel and convert the image to 8 bits per pixel. If the image in the IFD is a 24 bit per pixel image, the conversion process is defined by the 'tf_set_true_color_mode' routine. 24 bit True Color images are reduced to 8 bit images using either the 332-RGB, Dithered, or Adaptive Palette method. When 'mode' = 0, the 332-RGB method is used. The Red, Green, and Blue color components are compressed to 8 bit pixels consisting of 3 bits Red, 3 bits Green, and 2 bits Blue, and the Color Look Up Table is loaded with a compressed True Color palette. When 'mode' = 1, the Dithered method is used. Again a True Color palette is loaded, but the pixel intensities are modulated (or dithered) in a technique which approximates all of the 16 million possible colors. When 'mode' = 2, the Adaptive Palette method is used. In this case each 24 bit image is analyzed separately. The optimal color palette is determined for the image and loaded into the Color Look Up Table. The Adaptive Palette method reduces the 16 million possible colors in the 24 bit image down to 'num_colors', where 'num_colors' can range from 2 to 256. The 'quality' parameter lets the user optimize the Adaptive Palette algorithm for image quality. The valid range is from 0 to 100. When 'quality' is closer to 0, the algorithm is optimized for images with fewer colors, but many shades per color (smooth shading is emphasized at the expense of color variety). When 'quality' is closer to 100, the algorithm is optimized for images with a broader color distribution (many colors are accommodated at the expense of smooth shading). If 'mode' is not 2, the 'num_colors' and 'quality' parameters are ignored. Availability: In TIFF256 Graphics Library Version 3.0 and up. Page: 13 3.2.2 tf_get_true_color_mode(pmode,pnum_colors,pquality) Inputs: int *pmode,*num_colors,*pquality; Returns: Nothing Description: This routine returns the current True Color display mode and the Adaptive Palette configuration parameters which were set by 'tf_set_true_color_mode'. '*pmode' returns the True Color display 'mode' value, '*pnum_colors' returns the Adaptive Palette 'num_colors' value, and '*pquality' returns the Adaptive Palette 'quality' value. Availability: In TIFF256 Graphics Library Version 3.0 and up. 3.2.3 tf_open_file(filename) Inputs: char far filename[]; Returns: int fail_flag; Description: This routine opens the TIFF file specified by the character string 'filename[]' for use by the TIFF256 Extensions. Only one file can be opened at a time. The file is opened as 'Read Only'. If the file is successfully opened, this routine returns a '0'. Otherwise, it returns a '-1'. This routine must be called before calling tf_get_file_info(). Availability: In TIFF256 Graphics Library Version 1.0 and up. 3.2.4 tf_close_file() Inputs: Nothing Returns: Nothing Description: This routine closes the currently open TIFF file. This routine must be called before opening a new TIFF file with tf_open_file(). This routine should be called before exiting your program. Availability: In TIFF256 Graphics Library Version 1.0 and up. Page: 14 3.2.5 tf_get_file_info() Inputs: Nothing Returns: int fail_flag; Description: This routine verifies that the selected file is a TIFF format file. Then it initializes the TIFF256 environment for this file. The global parameter 'TF_Num_Ifd' is set to the number of Image File Directories (IFDs) existing within the file. An IFD is one 'picture', and multiple IFDs can exist within one TIFF file. The TIFF file pointer is set to point to the first IFD in the file. This routine is typically called after 'tf_open_file'. The 'fail_flag' is returned with one of the following values: 0 No Errors 1 Error, Reading file failed 2 Error, File shorter than expected 3 Error, Bad TIFF File Availability: In TIFF256 Graphics Library Version 1.0 and up. Comments: The 'fail_flag' return values 2 and 3 have been added as of Version 3.0. 3.2.6 tf_skip_ifd(count) Inputs: unsigned count; Returns: int reached_end; Description: This routine moves the TIFF file pointer ahead 'count' IFDs. Typically, this routine is called after tf_get_file_info() to index the TIFF file pointer to the desired IFD. For example, if tf_get_file_info() sets TF_Num_Ifd to 5, calling this routine immediately after tf_get_file_info() with 'count' = 3, will cause the TIFF file pointer to skip over the first 3 IFDs and point to the 4th IFD. If 'count' equals or exceeds the number of remaining IFDs, this routine returns a 1, and the TIFF file pointer is set to point to the last IFD. Otherwise it returns a 0. Availability: In TIFF256 Graphics Library Version 1.0 and up. Page: 15 3.2.7 tf_set_defaults() Inputs: Nothing Returns: Nothing Description: This routine sets the default values for all of the global parameters which are modified by TIFF 'Tags'. TIFF files may not include data for all of the parameters used by the TIFF256 environment, and therefore the defaults should be set. This routine should be called at the beginning of each new IFD, prior to calling tf_read_ifd(). The default values are listed below: TF_ImageWidth = 0 TF_ImageLength = 0 TF_BitsPerSample[0] = 1 TF_BitsPerSample[1] = 1 TF_BitsPerSample[2] = 1 TF_ResolutionUnit = 2 TF_SamplesPerPixel = 1 TF_PhotometricInterpretation = 1 TF_XResolution_int = 300 TF_XResolution_frac = 1 TF_YResolution_int = 300 TF_YResolution_frac = 1 Availability: In TIFF256 Graphics Library Version 1.0 and up. 3.2.8 tf_read_ifd() Inputs: Nothing Returns: int fail_flag; Description: This routine reads the data from the IFD currently pointed to by the TIFF file pointer. The TIFF file pointer must be pointing to a valid IFD prior to calling this routine (This routine is typically called after 'tf_open_file' or 'tf_skip_ifd' which initialize the pointer). After reading the data from the current IFD, the TIFF file pointer is set to point to the next IFD. If the TIFF file pointer points to the last IFD in the TIFF file and this routine is executed, the IFD is read, and then the TIFF file pointer is set with a null value. After calling this routine, 'tf_display_ifd' or 'tf_load_image' can be called to display the IFD's image. The 'fail_flag' is returned with one of the following values: Page: 16 0 No Errors 1 Error, TIFF file pointer is a null value, end of file 2 Error, Seeking in File 3 Error, Reading file failed 4 Greater than 8 Bit Palette Pixels Not Supported 5 Samples Per Pixel > 3 Not Supported 6 Only 8x8x8 Bit True Color Pixels Supported 7 Compressed TIFF data Not Supported 8 This Photometric Interpretation Not Supported 9 Currently Only Support up to 1024 Strips 10 Samples Per Pixel > 3 Not Supported 11 Currently Only Support up to 1024 Strips 12 This Planar Configuration Not Supported 13 This Predictor Not Supported 14 Color Map Size > 256 Not Supported The following global parameters are set by this routine: TF_ImageWidth TF_ImageLength TF_BitsPerSample[3] TF_ResolutionUnit TF_SamplesPerPixel TF_PhotometricInterpretation TF_XResolution_int TF_XResolution_frac TF_YResolution_int TF_YResolution_frac Availability: In TIFF256 Graphics Library Version 1.0 and up. Comments: The 'fail_flag' return values 2 through 14 have been added as of Version 3.0. 3.2.9 tf_display_ifd(x0,y0) Inputs: unsigned x0; unsigned y0; Returns: int fail_flag; Description: This routine displays the image that is defined in the IFD read by the most recent call to 'tf_read_ifd'. The image is drawn directly to the screen with its top left corner at screen coordinates 'x0,y0'. The Color Look Up Table is not modified until this routine is executed. When executed, this routine prepares the Color Look Up Table as Page: 17 defined by the IFD being displayed. Before calling this routine, 'tf_read_ifd' must be called to initialize all of the required parameters. When reading the image in the IFD, this routine automatically detects the number of bits per pixel and converts the image to 8 bits per pixel. If the image in the IFD is a 24 bit per pixel image, the conversion process is defined by the 'tf_set_true_color_mode' routine. If Adaptive Palette is enabled (via 'tf_set_true_color_mode'), this routine temporarily allocates 32k bytes of memory for the Adaptive Palette conversion process. If the allocation fails, this routine returns a fail_flag = 1, otherwise 0 is returned. In the case where the allocation fails, the program can disable Adaptive Palette and call this routine again. Typically this routine is used instead of 'tf_load_image' when you don't need to store the image in a buffer for subsequent manipulation. This routine also useful when the run time environment has insufficient memory for allocating the huge image memory buffer used with 'tf_load_image'. Availability: In TIFF256 Graphics Library Version 1.0 and up. Comments: This routine may be called more than once per 'tf_read_ifd' call. Please DO NOT call this routine if 'tf_read_ifd' returns an error (fail_flag = 1). 3.2.10 tf_save_file(x0,y0,x1,y1,filename) Inputs: unsigned x0,y0,x1,y1; char far filename[]; Returns: int fail_flag; Description: This routine saves the portion of the screen image defined by (x0,y0) (x1,y1) to the TIFF file "filename". The image is saved as an 8 bit Palette Color image (i.e. 8 bits/pixel). This routine may be called at anytime after vsa_init is called. If an error occurs in writing the file, a -1 is returned, otherwise 0 is returned. The TIFF image file saved as a result of this routine has the following characteristics, as defined by the TIFF specification: - Intel Byte Ordering - SamplesPerPixel = 1 - BitsPerSample = 8 (i.e. 8 bits per pixel) - ColorMap (i.e. Color palette stored within TIFF file) - PhotometricInterpretation = Palette Color - PlanarConfiguration = 1 - RowsPerStrip = 1 - ImageWidth = |x1-x0|+1 (pixels) Page: 18 - ImageLength = |y1-y0|+1 (pixels) - Resolution Unit = 2 (inches) - XResolution = 100 (Dots Per Inch) - YResolution = 100 (Dots Per Inch) - Compression = none Availability: In TIFF256 Graphics Library Version 2.0 and up. 3.2.11 tf_image_size() Inputs: Nothing Returns: long size; Description: This routine returns the size (in bytes) of the memory buffer required to store an image that is defined in the IFD read by the most recent call to 'tf_read_ifd'. Before calling this routine, 'tf_read_ifd' must be called to define all of the required global parameters. The size is based on 8 bit pixels regardless of the image type since 'tf_load_image' always converts to 8 bit pixels as it reads the TIFF file. The size returned is equal to the number of pixels in the image plus 4. Typically, after calling 'tf_image_size, a 'huge' memory buffer is allocated with 'size' bytes. Then the 'tf_load_image' function is used to load the image from the TIFF file into the memory buffer. Availability: In TIFF256 Graphics Library Version 3.0 and up. Comments: This routine may be called more than once per 'tf_read_ifd' call. Please DO NOT call this routine if 'tf_read_ifd' returns an error (fail_flag = 1). 3.2.12 tf_load_image(image,lut) Inputs: unsigned char huge *image; unsigned char far *lut; Returns: int colors; Description: This routine loads the 'image' memory buffer with the image that is defined in the IFD read by the most recent call to 'tf_read_ifd'. The images color palette is loaded into the 'lut' memory buffer. The 'image' memory buffer must be allocated the size returned by 'tf_image_size', and the 'lut' memory must be allocated 768 bytes before calling this routine. The return value 'colors' indicates how many of the 256 colors in 'lut' are actually used (0 or 1 indicates an error). Before calling this routine, 'tf_read_ifd' must be called to initialize all of the required parameters. Page: 19 When reading the image in the IFD, this routine automatically detects the number of bits per pixel and converts the image to 8 bits per pixel. If the image in the IFD is a 24 bit per pixel image, the conversion process is defined by the 'tf_set_true_color_mode' routine. If Adaptive Palette is enabled (via 'tf_set_true_color_mode'), this routine temporarily allocates 32k bytes of memory for the Adaptive Palette conversion process. If the allocation fails, this routine returns a fail_flag = 1. In the case where the allocation fails, the program can disable Adaptive Palette and call this routine again. The 'image' buffer can be displayed on the screen with the 'vsa_put_image' function, or saved to a TIFF file with the 'tf_save_image' function. The color palette in the 'lut' buffer can be loaded into the Color Look Up Table using the 'vsa_write_color_block' routine. The 'image' buffer stores the image width in the first two bytes, the image height in the second two bytes, and then the image pixels in raster order (row, then column). The first pixel value following image height is the top left corner pixel. The 'lut' array stores the 256 color palette data in RGB triplets where each of R, G, and B is a byte. 768 triplets are stored in 'lut'. Typically this routine is used instead of 'tf_display_ifd' when you need to store the image in a buffer for subsequent manipulation. With this routine, a program can bring in an image, manipulate its pixels and or color palette, and then save it back to a TIFF file without ever necessarily having to display the image on the screen. Availability: In TIFF256 Graphics Library Version 3.0 and up. Comments: This routine may be called more than once per 'tf_read_ifd' call. Please DO NOT call this routine if 'tf_read_ifd' returns an error (fail_flag = 1). 3.2.13 tf_save_image(image,lut,filename) Inputs: unsigned char huge *image; unsigned char far *lut; char filename[]; Returns: int fail_flag; Description: This routine saves the image defined in the 'image' buffer along with the 256 color palette defined in the 'lut' buffer to the TIFF file "filename". The image is saved as an 8 bit Palette Color image (i.e. 8 bits/pixel). This routine may be called at anytime after vsa_init is called, assuming that both 'image' and 'lut' have been loaded with meaningful data.. If an error occurs in writing the file, a -1 is returned, otherwise 0 is returned. Page: 20 The 'image' buffer could have been loaded through either a 'tf_load_image' (which gets it from a TIFF file) or through 'vsa_get_image' (which gets it directly from the screen). In the latter case, you would also need to have loaded the 'lut' buffer using 'vsa_read_color_block'. The 'image' array stores the image width in the first two bytes, the image height in the second two bytes, and then the image pixels in standard raster order (row, then column). First pixel is in top left corner. The 'lut' array stores the 256 color palette data in RGB triplets where each of R, G, and B is a byte. 256 triplets (768 bytes) are stored in 'lut'. The TIFF image file saved as a result of this routine has the following characteristics, as defined by the TIFF specification: - Intel Byte Ordering - SamplesPerPixel = 1 - BitsPerSample = 8 (i.e. 8 bits per pixel) - ColorMap (i.e. Color palette stored within TIFF file) - PhotometricInterpretation = Palette Color - PlanarConfiguration = 1 - RowsPerStrip = 1 - ImageWidth = first 16 bits of 'image' buffer - ImageLength = second 16 bits of 'image' buffer - Resolution Unit = 2 (inches) - XResolution = 100 (Dots Per Inch) - YResolution = 100 (Dots Per Inch) - Compression = none Availability: In TIFF256 Graphics Library Version 3.0 and up. 3.2.14 tf_set_prime_colors() Inputs: Nothing Returns: Nothing Description: This routine updates the prime color global parameters: TF_Black, TF_Red, TF_Orange, TF_Yellow, TF_Green, TF_Aqua, TF_Blue, TF_Violet, and TF_White. It does this by scanning the Color Look Up Table and loading each parameter with the Color Look Up Table index for the brightest color nearest to the color specified by the parameter name. This routine should be called following any operation which modifies the Color Look Up Table (such as tf_display_ifd). The prime color global parameters are provided in an attempt to give the user access to a standard set of colors (for use with text, borders, etc.) regardless of Color Look Up Table operations. However, the color must exist in the Color Look Up Table for this routine to find it. Availability: In TIFF256 Graphics Library Version 1.0 and up. Page: 21 4.0 Nitty Gritties 4.1 Registration Information If you find the TIFF256 Graphics Library Extensions useful, a registration of $29 would be appreciated ($15 if ordering VSA256 and TIFF256 at the same time, see ORDER.TXT). Registration brings with it MAJOR BENEFITS, as spelled out in section 1.2, so look at the ORDER.TXT file and fill it out! Please fill out the Information About You and the Wish List sections, and indicate the version number of the software you are presently using. Send check or money order to: Spyro Gumas 1668 Shady Brook Drive Fullerton, Ca. 92631 Page: 22 4.2 Software License TIFF256 Graphics Library, Version 3.0 Copyright Spyro Gumas, 1992 - 1994. All Rights Reserved. The TIFF256 Graphics Library Extensions is a "shareware program" and is provided at no charge to the user for evaluation. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using The TIFF256 Graphics Library Extensions and continue to use The TIFF256 Graphics Library Extensions after a reasonable trial period, you must make a registration payment of $29 to Spyro Gumas ($15 if ordering VSA256 and TIFF256 at the same time, see ORDER.TXT). The registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. You are free (and encouraged) to copy and distribute The TIFF256 Graphics Library Extensions if: 1) It is not used as a component of another software library. 2) No fee is charged for use, copying or distribution. 3) It is distributed as is (preferably as TIF256.ZIP) and not modified in any way. Furthermore, you are granted royalty free use of The TIFF256 Graphics Library Extensions executable code in any of your programs given that: 1) You have registered your use of The TIFF256 Graphics Library Extensions and paid the registration fee. 2) It is not used as a component of another software library. 3) You visibly acknowledge the use of The TIFF256 Graphics Library Extensions in your product in both the printed materials and the executable software with the following statement: "This software uses the VSA256 and TIFF256 Graphics Libraries, Copyright Spyro Gumas, 1992 - 1994. All Rights Reserved" Clubs and user groups may charge a nominal fee (not to exceed $10) for expenses and handling while distributing The TIFF256 Graphics Library Extensions. Anyone distributing The TIFF256 Graphics Library Extensions for any kind of remuneration must first Page: 23 contact Spyro Gumas at the address below for authorization. This authorization will be automatically granted to distributors recognized by the (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering The TIFF256 Graphics Library Extensions immediately (However Spyro Gumas must still be advised so that the distributor can be kept up-to-date with the latest version of The TIFF256 Graphics Library Extensions.). Commercial users of The TIFF256 Graphics Library Extensions must register and pay for their copies of The TIFF256 Graphics Library Extensions within 30 days of first use or their license is withdrawn. Consult the file ORDER.TXT for more information or contact Spyro Gumas. 4.3 Disclaimer Users of The TIFF256 Graphics Library Extensions must accept this disclaimer of warranty: The TIFF256 Graphics Library Extensions is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of The TIFF256 Graphics Library Extensions. In no event shall the author's liability for any damages ever exceed the price paid for the license to use The TIFF256 Graphics Library Extensions, regardless of the form of the claim. The person using The TIFF256 Graphics Library Extensions bears all risk as to the quality and performance of this software. 4.4 Technical Support If you have any questions or comments about The TIFF256 Graphics Library Extensions, please write me at: Spyro Gumas 1668 Shady Brook Drive Fullerton, Ca. 92631 Or, contact me on EMAIL! CompuServ 71064,1571 Internet: 71064.1571@compuserve.com Page: 24 5.0 Appendix 5.1 TIFF.H Include File /*................................. TIFF.H ................ 7-28-94 ........*/ /* This file declares the TIFFLB library functions and global parameters */ /* used throughout the graphics routines (Version 3.0). */ /* */ /* Copyright Spyro Gumas, 1992 - 1994. All Rights Reserved. */ /*..........................................................................*/ /*.... The next line is for compatibility with older versions of TIFF256 ...*/ #define tf_display_image tf_display_ifd /*..........................................................................*/ /* Function Prototypes */ /*..........................................................................*/ extern void far cdecl tf_set_true_color_mode(int, int, int); extern void far cdecl tf_get_true_color_mode(int far *, int far *, int far *); extern int far cdecl tf_open_file(char far *); extern void far cdecl tf_close_file(void); extern int far cdecl tf_get_file_info(void); extern int far cdecl tf_skip_ifd(unsigned); extern void far cdecl tf_set_defaults(void); extern int far cdecl tf_read_ifd(void); extern int far cdecl tf_display_ifd(unsigned,unsigned); extern int far cdecl tf_save_file(unsigned,unsigned,unsigned,unsigned, char far *); extern long far cdecl tf_image_size(void); extern int far cdecl tf_load_image(unsigned char huge*,unsigned char far*); extern int far cdecl tf_save_image(unsigned char huge*,unsigned char far*,char far *); extern void far cdecl tf_set_prime_colors(void); /*..........................................................................*/ /* Parameter Declarations */ /*..........................................................................*/ extern unsigned char far TF_Byte_Buf[4096]; extern unsigned long TF_ImageWidth, TF_ImageLength; extern unsigned far TF_BitsPerSample[3],TF_Num_Ifd; extern unsigned TF_ResolutionUnit,TF_SamplesPerPixel; extern unsigned TF_PhotometricInterpretation; extern unsigned long TF_XResolution_int,TF_XResolution_frac; extern unsigned long TF_YResolution_int,TF_YResolution_frac; extern unsigned TF_Black,TF_Red,TF_Orange,TF_Yellow,TF_Green; extern unsigned TF_Aqua,TF_Blue,TF_Violet,TF_White; Page: 25